/**
 * ============================================
 * 邮件服务配置模块
 *
 * 功能说明：
 * - 使用nodemailer库提供邮件发送功能
 * - 支持生成和发送邮件验证码
 * - 提供邮件服务连接验证
 * - 使用HTML模板美化邮件内容
 *
 * 使用说明：
 * - 需要配置SMTP服务器信息（QQ邮箱、Gmail等）
 * - 调用sendEmailCode函数发送验证码
 * - 验证码会自动生成并包含在邮件中
 * ============================================
 */

// 引入nodemailer库 - Node.js最流行的邮件发送库
const nodemailer = require('nodemailer');

/**
 * ====================
 * 创建邮件传输器
 * ====================
 * 功能：配置SMTP服务器连接，创建邮件传输实例
 * 支持SSL加密，确保邮件传输安全
 */
const transporter = nodemailer.createTransport({
  host: process.env.SMTP_HOST || 'smtp.qq.com',    // SMTP服务器地址，默认QQ邮箱
  port: process.env.SMTP_PORT || 587,              // SMTP端口，默认587
  secure: true,                                    // 使用SSL/TLS加密连接
  auth: {
    user: process.env.EMAIL_USER,                  // 发件邮箱用户名
    pass: process.env.EMAIL_PASSWORD,              // 发件邮箱密码或授权码
  },
});

/**
 * ====================
 * 生成随机验证码函数
 * ====================
 * 功能：生成6位数字验证码，用于邮件验证
 * 安全性：使用Math.random()生成随机数，确保验证码不可预测
 *
 * @returns {string} 6位数字验证码
 */
const generateEmailCode = () => {
  // 生成6位数字验证码（100000-999999之间的随机数）
  return Math.floor(100000 + Math.random() * 900000).toString();
};

/**
 * ====================
 * 发送邮件验证码函数
 * ====================
 * 功能：发送包含验证码的HTML格式邮件
 * 特性：支持自定义邮件主题和用途，自动生成美观的HTML模板
 *
 * @param {string} email - 收件人邮箱地址
 * @param {string} code - 验证码（可选，不提供时自动生成）
 * @param {string} purpose - 验证码用途，如'验证'、'注册'、'重置密码'等
 * @returns {Promise<Object>} 发送结果 {success: boolean, messageId?: string, error?: string}
 */
const sendEmailCode = async (email, code, purpose = '验证') => {
  try {
    // 如果没有提供验证码，自动生成一个
    const verificationCode = code || generateEmailCode();
    
    /**
     * 邮件配置选项
     * 包含发件人、收件人、主题和HTML内容
     */
    const mailOptions = {
      from: process.env.EMAIL_FROM,                                  // 发件人地址
      to: email,                                                     // 收件人地址
      subject: `${process.env.APP_NAME} - ${purpose}验证码`,         // 邮件主题
      html: `
        <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
          <h2 style="color: #333; text-align: center;">${process.env.APP_NAME}</h2>
          <div style="background: #f5f5f5; padding: 20px; border-radius: 5px;">
            <h3 style="color: #555;">您的${purpose}验证码</h3>
            <p style="font-size: 16px; color: #666;">验证码：<strong style="font-size: 24px; color: #007bff;">${verificationCode}</strong></p>
            <p style="font-size: 14px; color: #999;">验证码有效期：${process.env.EMAIL_CODE_EXPIRE || 600}秒</p>
            <p style="font-size: 12px; color: #999;">请勿将此验证码透露给他人。</p>
          </div>
        </div>
      `, // HTML邮件内容，使用内联样式确保兼容性
    };

    // 发送邮件
    const result = await transporter.sendMail(mailOptions);
    console.log(`✅ 邮件验证码已发送至 ${email}`);
    
    // 返回成功结果，包含邮件消息ID
    return {
      success: true,
      messageId: result.messageId,
      code: verificationCode // 返回实际发送的验证码，便于后续验证
    };
  } catch (error) {
    // 错误处理：记录错误并返回失败结果
    console.error('❌ 发送邮件验证码失败:', error);
    return {
      success: false,
      error: error.message
    };
  }
};

/**
 * ====================
 * 验证邮件传输器连接函数
 * ====================
 * 功能：测试SMTP服务器连接是否正常
 * 使用场景：应用启动时验证邮件服务可用性
 *
 * @returns {Promise<boolean>} 连接是否成功
 */
const verifyTransporter = async () => {
  try {
    // 使用verify()方法测试连接
    await transporter.verify();
    console.log('✅ 邮件服务连接成功');
    return true;
  } catch (error) {
    console.error('❌ 邮件服务连接失败:', error);
    return false;
  }
};

/**
 * ====================
 * 启动时验证连接
 * ====================
 * 功能：应用启动时自动验证邮件服务连接
 * 确保邮件服务在需要时可用
 */
verifyTransporter();

/**
 * ====================
 * 模块导出
 * ====================
 * 功能：导出邮件服务相关函数，供其他模块使用
 */
module.exports = {
  transporter,         // 邮件传输器实例，可用于发送其他类型的邮件
  generateEmailCode,   // 生成验证码函数
  sendEmailCode,       // 发送验证码邮件函数（主要使用这个）
  verifyTransporter,   // 验证连接函数
};